PagerDuty Events API V2を使用してインシデントを作成する方法

#PagerDuty

#CLI

るおん

2024.07.30

リテールアプリ共創部のるおんです。今回は、PagerDuty Events API V2 を使って、コマンドラインからCLIを用いてインシデントを作成するまでを実際にやってみたいと思います。
今回のブログの内容は、基本的にドキュメントに載っている内容ですが、英語のドキュメントしか見つからなかったため、PagerDutyを初めて使う方向けにその具体的な手順と、オプションの説明などをしたいと思います。

PagerDuty Events API V2とは

PagerDutyとは

そもそも PagerDuty とは、ITオペレーション、DevOps、セキュリティチームのためのインシデント管理プラットフォームです。様々な監視ツールやアプリケーションと統合し、アラートの集中管理、エスカレーション、オンコール管理などを行うことができます。24時間365日のサービス運用において、迅速なインシデント対応を可能にし、ダウンタイムの最小化に貢献します。

PagerDuty Events API V2の概要

PagerDuty Events API V2は、外部システムからPagerDutyにイベント（アラートやインシデント）を送信するためのAPIです。このAPIを使用することで、以下のようなことが可能になります：

新しいインシデントの作成（トリガー）
既存のインシデントの更新（確認や解決）
カスタム詳細情報の追加
インシデントへのリンクや画像の添付

PagerDutyには様々なAPIが用意されていますが、今回使用する PagerDuty Events API V2 は、これらのAPIの中でも特に外部システムからのアラート送信に特化しており、監視ツールやアプリケーションとPagerDutyを簡単に連携させるために広く使用されています。

今回は、CLIを使ってコマンドライン上からPagerDutyのインシデントを作成してみます。
公式ドキュメントはこちらです。

やってみる

セットアップ

もし、まだPageDutyのアカウントを持っていない場合は、PagerDutyのウェブサイトにアクセスし、アカウントを作成します。

アカウント登録については以下のブログで詳しく解説されています。

サービスを追加する

PagerDutyダッシュボードから「Services」→「Add New Service」を選択します。
スクリーンショット 2024-07-30 16.35.03
サービス名を入力し、「Integration Type」で「Events API V2」を選択します。
必要な情報を入力し、サービスを作成します。
スクリーンショット 2024-07-30 16.36.47

インテグレーションキーを取得する

作成したサービスの詳細ページで、「Integration Key」を確認します。このキーは後ほどAPIリクエストで使用するので控えておいてください。
スクリーンショット 2024-07-30 16.42.45

インシデントの作成

それでは、実際にCLIを使ってインシデントを作成してみましょう。
公式APIリファレンスはこちらです。
HTTPリクエストメソッドはPOSTで、エンドポイントはhttps://events.pagerduty.com/v2/enqueueです。
routing_keyのみ先ほど取得したkeyに置き換えて、以下のコマンドを打ち込んでみてください。

curl --request POST \
  --url https://events.pagerduty.com/v2/enqueue \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": {
    "summary": "test-app.exampleマシンのDISKが99%になりました。",
    "timestamp": "2024-07-30T08:42:58.315+0000",
    "severity": "critical",
    "source": "test-app.example.com",
    "component": "mysql",
    "group": "prod-datapipe",
    "class": "disk",
    "custom_details": {
      "free space": "1%",
      "ping time": "1500ms",
      "load avg": 0.75
    }
  },
  "routing_key": "YOUR_INTEGRATION_KEY",
  "dedup_key": "srv01/mysql",
  "event_action": "trigger",
  "client": "Sample Monitoring Service",
  "client_url": "https://monitoring.service.com",
  "links": [
    {
      "href": "http://pagerduty.example.com",
      "text": "An example link."
    }
  ],
  "images": [
    {
      "src": "https://chart.googleapis.com/chart?chs=600x400&chd=t:6,2,9,5,2,5,7,4,8,2,1&cht=lc&chds=a&chxt=y&chm=D,0033FF,0,0,5,1",
      "href": "https://google.com",
      "alt": "An example link with an image"
    }
  ]
}'

すると、以下の画像のようにインシデントが作成されるのが確認できると思います。
スクリーンショット 2024-07-30 16.59.53

以下はAPIの各パラメータの説明です。より詳細な説明は、公式APIリファレンスを参照してください。

payload: イベントの詳細情報を含むオブジェクト
summary: アラートの概要/タイトル（必須）
timestamp: イベントが発生した時刻（ISO 8601形式）
severity: イベントの重大度（critical/error/warning/info）
source: イベントの発生源（主に、ホスト名やドメイン名を入れます）
component: 影響を受けているコンポーネント（今回はmysql）
group: イベントのグループ化に使用
class: イベントの分類
custom_details: カスタム詳細情報（キーと値のペア）
routing_key: インテグレーションキー（必須）
dedup_key: 重複排除キー。同じキーを持つイベントは既存のインシデントに関連付けられる
event_action: イベントのアクション（trigger/acknowledge/resolve）
client: イベントを送信したクライアントの名前
client_url: クライアントのURL
links: 関連リンクの配列
href: リンクのURL
text: リンクのテキスト
images: 関連画像の配列
src: 画像のURL
href: 画像クリック時のリンク先URL
alt: 画像の代替テキスト

まとめ

PagerDuty Events API V2を使用することで、簡単にCLIからインシデントを作成できることがわかりました。この方法を使えば、既存の監視スクリプトやアプリケーションと統合してAPIリクエストを送信してインシデントを作成することができます。
今回はドキュメント通りの基本的な使い方を紹介しましたが、これからPagerDutyを使用しようとする方々のお役に立てれば幸いです。